SST ShlWAPI StrToInt Function

	(SST) ShlWAPI.pas Version 1.08

	Developer Reference

(SST)ShlWAPI StrToInt Function
Converts a literal, string representation of the integer part of a signed or unsigned number, in decimal notation, into a signed, 32-bit integer value.

Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).

Syntax
	function StrToInt(lpSrc : LPCSTR) : Integer;
	function StrToIntA(lpSrc : LPCSTR) : Integer; function StrToIntW(lpSrc : LPCWSTR) : Integer;

Parameters
lpSrc [in]	A pointer to a null-terminated string that contains the string represeantation of a number in the range from –2147483648 to 2147483647, in decimal notation.

Return Values
If the function was successful in converting the number represented by the string, it returns the value corresponding to the integer part of that number. If the input string represents a number in a notation other than decimal (e.g. hexadecimal, scientific), and/or the function is unable to convert the character representing the first digit into a numerical value, it returns zero.

Remarks
It should be borne in mind, that the function returns a signed, integer value, that is, strings representing values above 2147483647 will result in negative values being returned.
The function requires that the string consists exclusively of characters representing the digits 0 thru 9, and, optionally, the plus ("+") or minus ("-") sign. Nontheless, the function will convert string representations of the integer part of decimal numbers that contain a fractional part correctly. It is therefore possible to specify strings such as "123.987" or "543,012". However, the function does not recognize such strings as representations of floating point numbers, it merely ignores all parts of the string after the first invalid character it encoutners.
Separators such as commas, blanks, or periods, frequently used to group digits in numbers larger than 999, will cause the function to return erroneous results.
Some versions of the documentation accompanying Microsoft Software Development Kits, for example that, that shipped with Ms SDK version 6.1, state that the string representing the numerical value may, optionally, be preceded by a leading white space (e.g. a blank/space). Unfortunately this is false, a leading blank will cause the function to return 0.
To avoid compiler errors and/or calling the wrong function in Delphi source code that includes both the SystUtils and (SST)ShlWAPI units, the ShlWAPi function should be called using "ShlWAPI.StrToInt" (without the quotation marks).

Example
PROCEDURE TForm4.TestShlWAPIStrToInt(Sender : TObject); VAR numstr : STRING; VAR apiretval : INTEGER; VAR newinfoline : STRING; BEGIN numstr := ''; apiretval := 0; newinfoline := ''; numstr := IntToStr($FFFFFFFF); apiretval := ShlWAPI.StrToInt(PChar(numstr)); newinfoline := 'StrToInt called with "' + numstr + '" returned : '; newinfoline := newinfoline + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); apiretval := 0; numstr := FloatToStr(8888.77); apiretval := ShlWAPI.StrToInt(PChar(numstr)); newinfoline := 'StrToInt called with "' + numstr + '" returned : '; newinfoline := newinfoline + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); apiretval := 0; numstr := FloatToStr(10000.01); apiretval := ShlWAPI.StrToInt(PChar(numstr)); newinfoline := 'StrToInt called with "' + numstr + '" returned : '; newinfoline := newinfoline + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); apiretval := 0; numstr := '202 101'; apiretval := ShlWAPI.StrToInt(PChar(numstr)); newinfoline := 'StrToInt called with "' + numstr + '" returned : '; newinfoline := newinfoline + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); apiretval := 0; numstr := '-505030'; apiretval := ShlWAPI.StrToInt(PChar(numstr)); newinfoline := 'StrToInt called with "' + numstr + '" returned : '; newinfoline := newinfoline + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); apiretval := 0; numstr := '-600000,F91'; apiretval := ShlWAPI.StrToInt(PChar(numstr)); newinfoline := 'StrToInt called with "' + numstr + '" returned : '; newinfoline := newinfoline + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); apiretval := 0; numstr := 'ESP,F91'; apiretval := ShlWAPI.StrToInt(PChar(numstr)); newinfoline := 'StrToInt called with "' + numstr + '" returned : '; newinfoline := newinfoline + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); apiretval := 0; numstr := '1 000 000.01'; apiretval := ShlWAPI.StrToInt(PChar(numstr)); newinfoline := 'StrToInt called with "' + numstr + '" returned : '; newinfoline := newinfoline + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); apiretval := 0; numstr := '1,000,000.01'; apiretval := ShlWAPI.StrToInt(PChar(numstr)); newinfoline := 'StrToInt called with "' + numstr + '" returned : '; newinfoline := newinfoline + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); apiretval := 0; numstr := '0xAABBCCDD'; apiretval := ShlWAPI.StrToInt(PChar(numstr)); newinfoline := 'StrToInt called with "' + numstr + '" returned : '; newinfoline := newinfoline + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); apiretval := 0; Memo1.Lines.Add(''); END;
The above example produces the following output:
StrToInt called with "4294967295" returned : -1 (0xFFFFFFFF) StrToInt called with "8888.77" returned : 8888 (0x000022B8) StrToInt called with "10000.01" returned : 10000 (0x00002710) StrToInt called with "202 101" returned : 202 (0x000000CA) StrToInt called with "-505030" returned : -505030 (0xFFF84B3A) StrToInt called with "-600000,F91" returned : -600000 (0xFFF6D840) StrToInt called with "ESP,F91" returned : 0 (0x00000000) StrToInt called with "1 000 000.01" returned : 1 (0x00000001) StrToInt called with "1,000,000.01" returned : 1 (0x00000001) StrToInt called with "0xAABBCCDD" returned : 0 (0x00000000)

Requirements
Unit:	Declared and imported in (SST)ShlWAPI.pas
Library:	(SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode:	Implemented as ANSI (StrToInt and StrToIntA) and Unicode (StrToIntW) functions.
Min. ShlWAPI.dll version according to MS SDK doc.:	4.71
Min. ShlWAPI.dll version based on SST research:	4.71
Min. OS version(s) according to Microsoft SDK doc.:	Windows 2000, Windows NT 4.0 with Internet Explorer 4.0, Windows 98, Windows 95 with Internet Explorer 4.0
Min. OS version(s) according to SST research.:	Windows NT 4.0 with IE 4.0, Windows 95 with IE 4.0, Windows 98, Windows 2000 and later

See Also
StrToIntEx.

Windows APIs: StrToInt, StrToInt64Ex, StrToIntEx.

Document/Contents version 1.00
Page/URI last updated on 07.12.2023

Copyright © Stoelzel Software Technologie (SST) 2010 - 2017

Suggestions and comments mail to:
webmaster@stoelzelsoftwaretech.com